

%        File: cyclus.tex
%     Created: Sun Mar 28 02:00 PM 2010 C
% Last Change: Sun Mar 28 02:00 PM 2010 C
%
\documentclass[letterpaper]{article}
\usepackage[top=1.0in,bottom=1.0in,left=1.0in,right=1.0in]{geometry}
\usepackage{verbatim}
\usepackage{amssymb}
\usepackage{graphicx}
\usepackage{longtable}
\usepackage{amsfonts}
\usepackage{amsmath}
\usepackage[utf8]{inputenc}
\usepackage[usenames]{color}
\usepackage[
naturalnames = true, 
colorlinks = true, 
linkcolor = Black,
anchorcolor = Black,
citecolor = Black,
menucolor = Black,
urlcolor = Blue
]{hyperref}
%\usepackage{hyperref}
\usepackage{uml}
\author{P.P.H. Wilson, K. Huff\\ 
\href{mailto:wilsonp@engr.wisc.edu}{\texttt{wilsonp@engr.wisc.edu}}\\ 
\href{mailto:khuff@cae.wisc.edu}{\texttt{khuff@cae.wisc.edu}}
}
\date{}
\title{	\textsc{ Cyclus}:\\
An Object Oriented Fuel Cycle Code}
\begin{document}
\maketitle
\section*{Introduction}
\paragraph{}
As a successor to GENIUS, the next-generation fuel cycle systems analysis simulation tool, \textsc{ Cyclus}, will preserve many of the key features with a software architecture that provides a great deal of flexibility, both in terms of modifying the underlying modeling algorithms and presenting different levels of complexity to different users.
\paragraph{}
The \textsc{ Cyclus} modeling paradigm will let users reconfigure the basic building blocks of a simulation without changing the software.  The foundation of a simulation will be a commodity market that collects offers and requests and matches them according to some algorithm.  The user will be able to select which type of algorithm is used for each market by selecting a MarketModel and configure it with a particular set of parameters defined by that MarketModel.  Changing the parameters of a market will change its performance and selecting a different MarketModel will completely change its behavior.
\begin{itemize}
	\item{Beginning users:} Use predefined market configurations
	\item{Intermediate users:} Change parameters for a preselected MarketModel
	\item{Advanced users:} Select an alternate MarketModel
	\item{Developers:} Implement a new MarketModel
\end{itemize}
\paragraph{}
Facilities will be deployed to issue offers and requests in these markets.  Like markets, the user will be able to select which type of algorithm is used for each facility by selecting a FacilityModel and configure it with a particular set of parameters defined by that FacilityModel.  Changing the parameters of a facility will change its performance and selecting a different FacilityModel will completely change its behavior.  Unlike markets, multiple independent instances of each facility configuration can be deployed to represent individual facilities.
\begin{itemize}
	\item{Beginning users:} Deploy predefined facility configurations
	\item{Intermediate users:} Change parameters for one or more preselected FacilityModels
	\item{Advanced users:} Select an alternate FacilityModel 
	\item{Developers:} Implement a new FacilityModel
\end{itemize}


\paragraph{}
As with GENIUS, each instance of a facility will be associated with a defined Institution and each institution will operate in a geographically defined Region.
\paragraph{}
To reimplement the capabilities of GENIUS V2 in this paradigm requires the development of a MarketModel that implements a network flow algorithm, a ReactorFacilityModel that implements fuel burnup by table lookup and a SeparationsFacilityModel that implements a simple elemental separations matrix, among others.
\section{Components}
\subsection{Markets}
\paragraph{}
The foundation of a scenario is a set of commodity markets, each collecting offers and requests for a single commodity and matching them according to some algorithm.  The user can include as few/many different commodities as they wish to consider without any changing the software itself. Only one global market may be created for each commodity.  A market is defined by selecting a MarketModel and describing the parameters for that market using that model.  
\paragraph{}
In order to accommodate different algorithms for matching offers and requests, different MarketModels will be available. Each MarketModel defines its own set of parameters allowing a wide array of different algorithms.  The same MarketModel can be used for multiple commodities in the same problem, each with values chosen for the MarketModelParameters that are specific to that commodity. Conversely, the market for each commodity could be based on a different MarketModel.
\subsection*{Facilities}
For each of the global regions, the user defines available facility configurations that can operate in those markets.  Multiple facility configurations will typically be created in each region, including one or more reactor configurations (AP1000  vs ESBWR vs EPR – or PWR vs. HTGR vs CANDU) and one or more configurations for other facility types.  The user is free to choose the level of detail used in distinguishing one facility configuration from another.  Each facility configuration will either be a supplier in one or more global markets, a consumer in one or more global markets, or both a supplier and consumer in non-intersecting sets of global markets.  The set of facility configurations defines which facilities are available for deployment in a given scenario, but multiple instances of each facility configuration may exist.
\paragraph{}
A facility configuration is created by selecting a FacilityModel and defining the parameters for that facility configuration using that model.  Each FacilityModel will define its own set of parameters that govern its performance.  The same FacilityModel may be used for multiple facility configurations in the same region, each with parameters values appropriate for that facility configuration.


\subsection{Materials}
The Materials class is the primary unit of information in \textsc{Cyclus}. Materials passed, traded, and modified between and within facilities in the simulation are recorded at every timestep. This material history is stored in the output dataset of \textsc{Cyclus}. In addition to holding the map of isotopes and their masses, a material object has many attributes such as a chemical form gas, liquid, or solid, a commodity type traded on a market such as yellow cake, unenriched UF$_6$, enriched UF$_6$, used fuel, waste, etc. The numbor of isotopes that \textsc{Cyclus}.

\section{Implementing Object Oriented Design Patterns}
\textsc{Cyclus} will implement a structure that takes advantage of object-oriented software design techniques in order to create an extensible and modular user and developer interface. A primary workhorse for this implementation is the notion of design patterns, specifically the canonical Factory design pattern in which the shared interface of polymorphic objects is abstracted from the logic of their instantiation by a `factory' class.  
\paragraph{Abstraction}
The notion of the Factory class in \textsc{Cyclus} allows a level of abstraction to exist between the simulation and Facility instantiation as well as between Facility instantiation and behavior.
An interface defines the set of shared functions of a set of subclasses in an abstract superclass. In \textsc{Cyclus} main superclasses are Facility and Market while their subclasses are the concrete types of Facilities and Markets (e.g RecipeFac, NullFac, NetFlowMkt, ContractMkt). The interface for the Facility class is the set of virtual functions declared in the Facility class such as getName, getID, executeOrder(), sendMaterial(), receiveMaterial() etc. Through such an interface, the members of a subclass can be treated as interchangeable (polymorphic) instantiations of their shared superclass. 
%\paragraph{Instantiation}
%Instantiation is what happens when a concrete member of a class is brought into being with a constructor. A constructor will be called with initial parameters specific to this concrete object instance. Instantiation of an object of a class occurs with the line ``return new ''.
\paragraph{Modularity and Extensibility}
A modular code will have the traits of encapsulation and abstraction appropriate for a user or developer to flexibly make alterations to the simulation performance with minimal modification to the code. An extensible code should be both robustly suited to the addition of classes and subclasses and communication with other codes. Addition of new facilities or markets should be possible without any alteration of the software trunk. Much of this functionality will be made possible by a self-registration function in the factory pattern implementation. The modular design of \textsc{Cyclus} will stress avoidance of rigidity, in which changes to the code are potentially difficult, and fragility, in which changes to the code are potentially damaging.



\section*{User Experiences}
\subsection*{Beginning User}
The beginning user is able to choose from a set of configurations (models and definition parameters) from a database provided with \textsc{Cylcus}. Such a database should contain canonical benchmark configurations, unit testing configurations, and other configurations of interest.

After defining a region institution hierarchy, the beginning user compiles a set of configurations available to those institutions and regions within the simulation. Though the user can choose to provide a set of facilities that fully complete a mine to repository worldwide fuel cycle, it is unnecessary. They can instead choose to provide arbitrary sources and sinks of materials to replace the specific facilities of the fuel cycle that are unimportant in their fuel cycle analysis.

Simulations run by beginning users will employ:
\begin{itemize}
	\item{Unique region-institution hierarchies.}
	\item{Unique regional demand curves (facility deployment magnitudes).}
	\item{Preselected facility performance parameters.}
	\item{Preselected facility behavior models.}
\end{itemize}
A user could employ a simulation of this type to study robustness of support ratios, regional interaction studies, etc.

\subsection*{Intermediate User}
The intermediate user will be capable of customizing facility configurations by specifying parameters that alter the performance of that facility model. The parameters available to input specification will be unique to the facility model at hand. For example, while all facilities invite input specification of parameters such as their lifetime, construction time, and decommisioning time, a `recipe-based' reactor model will also allow input specification of a fresh fuel recipe, a spent fuel recipe, a total core weight, cycle time, etc.

Simulations run by intermediate users will employ:
\begin{itemize}
	\item{Unique region-institution hierarchies.}
	\item{Unique regional demand curves (facility deployment magnitudes).}
	\item{Unique facility performance parameters.}
	\item{Preselected facility behavior models.}
\end{itemize}

An intermediate user could employ a simulation of this type to make facility performance comparisons, investigate specific deployments of interest, conduct facility performance sensitivity studies, etc.
\subsection*{Advanced User}
The advanced user will both comfortably alter parameters and exchange facility models. That is, while default configurations will exist for all models, and many models can be used interchangeably for certain facilities, a recipe based separations model and a matrix separations model will conduct the calculation of their output isotope vectors in different ways. Similarly, different facility models will invite specification of different input parameters. That is, a recipe-based reactor model will invite specification of fresh and spent recipes, while a burnup-approximation reactor model will invite specification of desired burnup, acceptance windows, etc.

Simulations run by advanced users will employ:
\begin{itemize}
	\item{Unique region-institution hierarchies.}
	\item{Unique regional demand curves (facility deployment magnitudes).}
	\item{Unique facility performance parameters.}
	\item{A variety of provided facility behavior models.}
\end{itemize}

Advanced users will be able to conduct simulations analyzing modeling techniques, facility performance sensitivity, etc.  

\subsection*{Developer}
Open source code must be opent to collaborators who add content while being independently robust against comprimising changes by the user. In order to avoid rigidity in the first case and fragility in the second case, \textsc{Cyclus} implements a factory design pattern with levels of abstraction to decouple facility instantiation logic from the performance of the simulation. \textsc{Cyclus} developers will have great freedom to design and implement facility and market models of their own. 

Simulations run by developers will employ:
\begin{itemize}
	\item{Unique region-institution hierarchies.}
	\item{Unique regional demand curves (facility deployment magnitudes).}
	\item{Unique facility performance parameters.}
	\item{Unique, developer-customized facility behavior models.}
\end{itemize}

\paragraph{Market Model Development}
In order to implement a new market model, the developer should have to create only a new myMkt class in independent myMkt.cpp and myMkt.h files. In this class they must register their type by calling the function RegisterMkt(\emph{type} myType). In order for this to be possible, it must be constructed in such a way as to inherit Market class functionality. Finally, any Market model must perform only the following basic actions:
\begin{itemize}
	\item{collect requests}
	\item{collect offers}
	\item{match offers with requests}
	\item{pass back orders to suppliers and consumers}
\end{itemize}

\paragraph{Facility Model Development}
Similarly, in order to implement a new facility model, the developer should have to create only a new myFac class in independent myFac.cpp and myFac.h files. In this class they must register their type by calling the function RegisterFac(\emph{type} myType). In order for this to be possible, it must be constructed in such a way as to inherit the Facility, Region, and Institution classes. Finally, any Facility model must perform only the following basic actions:
\begin{itemize}
	\item{make one or more offers or requests}
	\item{receive and/or send material}
	\item{pass material and behavior history to the bookeeper}
\end{itemize}


\pagebreak
\subsubsection*{Facility Factory Design}
\begin{figure}[h!]
\begin{center}
\umlDiagram[box=,border,sizeX=11cm,sizeY=10cm, ref=diagram]{
\umlClass[ref=Facility, pos=\umlTopLeft{diagram}, posDelta={1em,-10em}]{Facility}{}{
		\umlMethod[visibility]{\emph{receiveMaterial}}{}
		\umlMethod[visibility]{\emph{sendMaterial}   }{}
		\umlMethod[visibility]{\emph{sendRequest}    }{}
		\umlMethod[visibility]{\emph{executeOrder}   }{}
		\umlMethod[visibility]{\emph{register}       }{\emph{Fac} type}
		}
\umlPlaceNode[bottom, down=7em, left=5em]{Facility}{FNode}
\umlSubclass{FNode}{Facility}
\umlClass[ref=Region, pos=\umlTopLeft{diagram}, posDelta={12em,-10em}]{Region}{
		}{
    \umlAttribute[visibility, type = string]{name}
    \umlAttribute[visibility, type = vector]{demand}
		\umlMethod[visibility]{getRegID  }{}
		}
\umlPlaceNode[bottom, down=6em, left=5em]{Region}{RNode}
\umlSubclass{RNode}{Region}
\umlClass[ref=Inst, pos=\umlTopLeft{diagram}, posDelta={22em,-10em}]{Inst}{
    \umlAttribute[visibility, type=string]{name}
    \umlAttribute[visibility, type=int]{taxRate}
		\umlAttribute[visibility, type=int]{interestRate}}
		{
		\umlMethod[visibility]{getInstID  }{}
		}
\umlPlaceNode[bottom, down=5em, left=5em]{Inst}{INode}
\umlSubclass{INode}{Inst}
\umlClass[pos=\umlTopRight{diagram}, posDelta={-20em,-8em}]{FacFactory}{
  \umlAttribute[visibility=\#, type= static]{registeredFacTypes}}{
	\umlMethod[visibility, returntype=Facility]{createFac}{\emph{FacilityId} id}
	}
\umlPlaceNode[bottom, down=6em, left=10em]{FacFactory}{FactoryNode}
\umlInstance{FactoryNode}{FacFactory}
\umlClass[pos=\umlBottomLeft{diagram}, posDelta={1em, 1em}]{NullFac}{}{
		\umlMethod[visibility]{receiveMaterial}{}
		\umlMethod[visibility]{sendMaterial   }{}
		\umlMethod[visibility]{sendRequest    }{}
		\umlMethod[visibility]{executeOrder   }{}
		\umlMethod[visibility]{register       }{\emph{Fac} type}
	}
\umlClass[pos=\umlBottomLeft{diagram}, posDelta={12em,1em}]{RecipeFac}{}{
		\umlMethod[visibility]{receiveMaterial}{}
		\umlMethod[visibility]{sendMaterial   }{}
		\umlMethod[visibility]{sendRequest    }{}
		\umlMethod[visibility]{executeOrder   }{}
		\umlMethod[visibility]{register       }{\emph{Fac} type}
}
\umlClass[pos=\umlBottomLeft{diagram}, posDelta={23em,1em}]{SourceFac}{}{
		\umlMethod[visibility]{receiveMaterial}{}
		\umlMethod[visibility]{sendMaterial   }{}
		\umlMethod[visibility]{sendRequest    }{}
		\umlMethod[visibility]{executeOrder   }{}
		\umlMethod[visibility]{register       }{\emph{Fac} type}
}
\umlClass[pos=\umlBottomLeft{diagram},posDelta={34em,1em}]{SinkFac}{}{
		\umlMethod[visibility]{receiveMaterial}{}
		\umlMethod[visibility]{sendMaterial   }{}
		\umlMethod[visibility]{sendRequest    }{}
		\umlMethod[visibility]{executeOrder   }{}
		\umlMethod[visibility]{register       }{\emph{Fac} type}
}
	\umlAssociation[pos=2em]{NullFac}{FNode}
	\umlAssociation[armB=6em]{RecipeFac}{FNode}
	\umlAssociation[armB=17em]{SourceFac}{FNode}
	\umlAssociation[armB=26em]{SinkFac}{FNode}
	\umlAssociation[armB=-5em]{NullFac}{RNode}
	\umlAssociation[armB=2em]{RecipeFac}{RNode}
	\umlAssociation[armB=10em]{SourceFac}{RNode}
	\umlAssociation[armB=17em]{SinkFac}{RNode}
	\umlAssociation[armB=-14em]{NullFac}{INode}
	\umlAssociation[armB=-6em]{RecipeFac}{INode}
	\umlAssociation[pos=2em]{SourceFac}{INode}
	\umlAssociation[armB=10em]{SinkFac}{INode}
	\umlInstance[armB=-22em]{NullFac}{FactoryNode}
	\umlInstance[armB=-17em, pos=2em]{RecipeFac}{FactoryNode}
	\umlInstance[armB=-10em, pos=2em]{SourceFac}{FactoryNode}
	\umlInstance[armB=-1em,pos=2em]{SinkFac}{FactoryNode}
	}
\end{center}
\caption{NullFac, RecipeFac, SourceFac, and SinkFac are some examples of FacilityModels instantiated by the FacFactory class and inheriting from the Facility, Institution, and Region classes} \label{fig: fac}
\end{figure}

%-----------------------------------------------------------------%
\subsubsection*{Market Factory Design}
\begin{center}
\umlDiagram[box=,border,sizeX=11cm,sizeY=10cm, ref=diagram]{
\umlClass[ref=Market, pos=\umlTopLeft{diagram}, posDelta={1em,-10em}]{Market}{}{
\umlMethod[visibility]{\emph{receiveOffers}      }{}
		\umlMethod[visibility]{\emph{receiveRequests}}{}
		\umlMethod[visibility]{\emph{solve}          }{}
		\umlMethod[visibility]{\emph{sendOrders}     }{}
		\umlMethod[visibility]{\emph{register}       }{\emph{Mkt} type}
		}
\umlPlaceNode[bottom, down=2em, left=5em]{Market}{FNode}
\umlAssociation{Market}{FNode}
\umlClass[pos=\umlTopRight{diagram}, posDelta={-20em,-8em}]{MktFactory}{
  \umlAttribute[visibility=\#, type=static]{registeredMktTypes}}{
	\umlMethod[visibility, returntype=Market]{createMkt}{\emph{MarketId} id}
	}
\umlPlaceNode[bottom, down=2em, left=10em]{MktFactory}{FactoryNode}
\umlAssociation{MktFactory}{FactoryNode}
\umlClass[pos=\umlBottomLeft{diagram}, posDelta={1em, 1em}]{NullMkt}{}{
		\umlMethod[visibility]{receiveOffers   }{}
		\umlMethod[visibility]{receiveRequests }{}
		\umlMethod[visibility]{solve           }{}
		\umlMethod[visibility]{sendOrders      }{}
		\umlMethod[visibility]{register        }{\emph{Mkt} type}
	}
\umlClass[pos=\umlBottomLeft{diagram}, posDelta={12em,1em}]{NetFlowMkt}{}{
		\umlMethod[visibility]{receiveOffers  }{}
		\umlMethod[visibility]{receiveRequests}{}
		\umlMethod[visibility]{solve          }{}
		\umlMethod[visibility]{sendOrders     }{}
		\umlMethod[visibility]{register       }{\emph{Mkt} type}
}
\umlClass[pos=\umlBottomLeft{diagram}, posDelta={23em,1em}]{SourceMkt}{}{
		\umlMethod[visibility]{receiveOffers  }{}
		\umlMethod[visibility]{receiveRequests}{}
		\umlMethod[visibility]{solve          }{}
		\umlMethod[visibility]{sendOrders     }{}
		\umlMethod[visibility]{register       }{\emph{Mkt} type}
}
\umlClass[pos=\umlBottomLeft{diagram},posDelta={34em,1em}]{ContractMkt}{}{
		\umlMethod[visibility]{receiveOffers  }{}
		\umlMethod[visibility]{receiveRequests}{}
		\umlMethod[visibility]{solve          }{}
		\umlMethod[visibility]{sendOrders     }{}
		\umlMethod[visibility]{register       }{\emph{Mkt} type}
}
	\umlSubclass{NullMkt}{FNode}
	\umlSubclass{NetFlowMkt}{FNode}
	\umlSubclass{SourceMkt}{FNode}
	\umlSubclass{ContractMkt}{FNode}
	\umlInstance{NullMkt}{FactoryNode}
	\umlInstance{NetFlowMkt}{FactoryNode}
	\umlInstance{SourceMkt}{FactoryNode}
	\umlInstance{ContractMkt}{FactoryNode}
}%
\end{center}
\end{document}


